<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta content="text/html; charset=ISO-8859-1"
 http-equiv="content-type">
  <title>LoggerConfiguration</title>
</head>
<body>
<h1>GEF and commons-logging<br>
</h1>
<br>
By using commons-logging, the logging package can be changed easily and
does not force users of the GEF package to use Log4J, which has been
hard-coded into the GEF class files. Many people are now using the <code>java.util.logging</code>
package that was introduced with Java 1.4. Converting the GEF code to
use commons-logging is pretty much just a search and replace. Now the
end user can specify a specific logging package of their choice.<br>
<br>
What follows is a fairly detailed description of using each logger
supported by commons-logging. This will be of use to developers who are
integrating GEF into their application. But first, I'll start off with
an overview of logging aimed at GEF developers themselves.<br>
<br>
<h2>Using commons-logging in GEF</h2>
The modifications to the GEF source code to convert from log4j to
commons-logging are minimal. For each file that used log4j logging,
these changes were made:<br>
<br>
Replaced: <br>
<code>import org.apache.log4j.*;</code><br>
<br>
With: <br>
<code>import org.apache.commons.logging.*;<br>
import org.apache.commons.logging.impl.*;<br>
<br>
</code>
<p>Replaced lines like:<br>
<code>private static Logger LOG =
Logger.getLogger(DefaultGraphModel.class);</code><br>
</p>
<p>With:<br>
<code>private static Log LOG =
LogFactory.getLog(DefaultGraphModel.class);<br>
</code></p>
<p>Several modifications were made to the build file, specifically in
the <code>init</code> and <code>run</code> targets. The <code>init </code>target
introduces several new properties to allow the developer to change out
the logging system easily, the <code>run </code>target was modified
to use those new properties. The default values for the properties set
the logging system to use log4j exactly as it has been used in previous
releases of GEF. <br>
</p>
<p>To use a different logger requires modification of the <code>${user.home}/.ant.properties
file</code>. As this file defines properties for use by the individual
developers and is not included with the GEF distribution, it is
possible for each developer to use the logging system of their choice.
The following example <code>.ant.properties</code> file shows settings
to use the Jdk14Logger:</p>
<p><code>logger=org.apache.commons.logging.impl.Jdk14Logger<br>
logger.configuration.name=java.util.logging.config.file<br>
logger.configuration.value=logger.properties</code><br>
</p>
<p>The <code>logger </code>property specifies the commons-logging
logger to use and tells commons-logging to use the Jdk14Logger.<br>
The <code>logger.configuration.name</code> property is the name of a
property to pass to java to specify the logger configuration settings,
and <code>logger.configuration.value</code> is the value of the logger
configuration settings. In this example, the java command is passed<br>
</p>
<p><code>-Djava.util.logging.config.file=logger.properties<br>
</code></p>
<p>This tells java to use the settings in a file named
logger.properties to set up the java.util.logging framework. See below
for an example of settings found in the logger.properties file. I have
added a basic logging.properties file for using the Jdk14Logger that
does output similarly to that produced by the default Log4J settings.<br>
</p>
<p>By way of comparison, these settings could be placed in your <code>.ant.properties</code>
file to specify that Log4J be used:<br>
</p>
<p><code>logger=org.apache.commons.logging.impl.Log4JLogger<br>
logger.configuration.name=log4j.configuration<br>
logger.configuration.value=log4j.properties</code><br>
</p>
<p>These are in fact the default settings in the build file.<br>
<code></code></p>
<code></code><br>
<code></code>
<h2>Integration with other applications</h2>
In the following, I describe changing the logging system from the
command line or from an Ant build file. As most of the settings are
simple property settings, they can also be done from within your code.<br>
<br>
To specify a specific logger be used, set this system property:<br>
<br>
<code>org.apache.commons.logging.Log</code><br>
<br>
to one of:<br>
<code>org.apache.commons.logging.impl.Log4JLogger<br>
org.apache.commons.logging.impl.Jdk14Logger<br>
org.apache.commons.logging.impl.SimpleLog<br>
org.apache.commons.logging.impl.LogKitLogger</code><br>
<br>
Where Log4JLogger is the Log4J logger, Jdk14Logger uses the Java 1.4+
java.util.logging classes, SimpleLog sends all messages to <code>System.err</code>,
and LogKitLogger uses the Avalon LogKit logging system.<br>
<br>
For example:<br>
<br>
<code>java
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JLogger
MyClass</code><br>
<br>
will cause MyClass to use the Log4J logger.<br>
<br>
By default, the commons-logging framework will attempt to use loggers
in this order:<br>
1. Log4J<br>
2. Jdk 1.4 logger<br>
3. Simple log<br>
<br>
So if the <code>org.apache.commons.logging.Log</code> property is not
set and Log4J is found in the classpath, it will be used. Otherwise, if
the JVM is version 1.4
or later, the java.util.logging classes will be used. Failing that, the
built-in
SimpleLog will be used.<br>
<br>
<br>
<span style="font-weight: bold;">To set up Log4JLogger:</span><br>
Make sure log4j.jar is in the classpath for the application.<br>
Set this system property:<br>
<br>
<code>log4j.configuration</code><br>
<br>
to the name of a property file containing the configuration settings
for log4j,<br>
for example:<br>
<br>
<code>log4j.configuration=log4j.properties</code><br>
<br>
See the log4j home pages for documentation on the specific
configuration settings.<br>
<br>
For example:<br>
<br>
<code>java
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JLogger
\<br>
-Dlog4j.configuration=log4j.properties MyClass</code><br>
<br>
will cause MyClass to use the Log4J logger with the configuration
settings<br>
found in log4j.properties.<br>
<br>
Here's an example of setting this up in an Ant build file:<br>
<pre>      <font color="#0000ff">&lt;</font><font color="#000000"><strong>java</strong></font><font
 color="#0000ff"> </font><font color="#0000ff">classname=</font><font
 color="#3333ff">"</font><font color="#3333ff">LogTest</font><font
 color="#3333ff">"</font><font color="#0000ff"> </font><font
 color="#0000ff">fork=</font><font color="#3333ff">"</font><font
 color="#3333ff">true</font><font color="#3333ff">"</font><font
 color="#0000ff">&gt;</font><br>         <font color="#0000ff">&lt;</font><font
 color="#009999"><strong>classpath</strong></font><font color="#0000ff"> </font><font
 color="#0000ff">refid=</font><font color="#3333ff">"</font><font
 color="#3333ff">classpathref</font><font color="#3333ff">"</font><font
 color="#0000ff">/&gt;</font><br>         <font color="#0000ff">&lt;</font><font
 color="#0000ff">jvmarg</font><font color="#0000ff"> </font><font
 color="#0000ff">value=</font><font color="#3333ff">"</font><font
 color="#3333ff">-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JLogger</font><font
 color="#3333ff">"</font><font color="#0000ff">/&gt;</font><br>         <font
 color="#0000ff">&lt;</font><font color="#0000ff">jvmarg</font><font
 color="#0000ff"> </font><font color="#0000ff">value=</font><font
 color="#3333ff">"</font><font color="#3333ff">-Dlog4j.configuration=log4j.properties</font><font
 color="#3333ff">"</font><font color="#0000ff">/&gt;</font><br>      <font
 color="#0000ff">&lt;</font><font color="#0000ff">/</font><font
 color="#000000"><strong>java</strong></font><font color="#0000ff">&gt;</font>   <br></pre>
<br>
<br>
<span style="font-weight: bold;">To set up Jdk14Logger:</span><br>
Set this system property:<br>
<br>
<code>org.apache.commons.logging.Log=org.apache.commons.logging.impl.Jdk14Logger</code><br>
<br>
For example:<br>
<br>
<code>java
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Jdk14Logger
MyClass</code><br>
<br>
will cause MyClass to use the Jdk14 logger.<br>
<br>
The Jdk14 logger can be configured as follows:<br>
<br>
Set a property named "handler" to a white-space separated list of <br>
java.util.logging Handler classes, for example:<br>
<br>
<code>handler=java.util.logging.ConsoleHandler
java.util.logging.FileHandler</code><br>
<br>
The log level can be set per logger or for all loggers at once, for
example:<br>
<br>
<code>.level=INFO</code><br>
<br>
will cause all loggers to log at INFO level. Better yet, these
properties can be<br>
put into a file, then used like this:<br>
<br>
<code>java
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Jdk14Logger
\<br>
-Djava.util.logging.config.file=logging.properties MyClass</code><br>
<br>
Here's an example property file:<br>
<br>
<pre><code>--------------------------------------------------------------------------------</code></pre>
<pre><code># logging.properties<br># jdk handlershandlers=java.util.logging.ConsoleHandler java.util.logging.FileHandler</code></pre>
<pre><code># default log level<br>.level=INFO</code></pre>
<pre><code># log level for the "DEBUG" logger<br>DEBUG.level=FINE</code></pre>
<pre><code># log file name for the FileHandler<br>java.util.logging.FileHandler.pattern=java%u.log</code></pre>
<pre><code>--------------------------------------------------------------------------------</code></pre>
<br>
Here's an example of setting this up in an Ant build file:<br>
<pre>      <font color="#0000ff">&lt;</font><font color="#000000"><strong>java</strong></font><font
 color="#0000ff"> </font><font color="#0000ff">classname=</font><font
 color="#3333ff">"</font><font color="#3333ff">LogTest</font><font
 color="#3333ff">"</font><font color="#0000ff"> </font><font
 color="#0000ff">fork=</font><font color="#3333ff">"</font><font
 color="#3333ff">true</font><font color="#3333ff">"</font><font
 color="#0000ff">&gt;</font><br>         <font color="#0000ff">&lt;</font><font
 color="#009999"><strong>classpath</strong></font><font color="#0000ff"> </font><font
 color="#0000ff">refid=</font><font color="#3333ff">"</font><font
 color="#3333ff">classpathref</font><font color="#3333ff">"</font><font
 color="#0000ff">/&gt;</font><br>         <font color="#0000ff">&lt;</font><font
 color="#0000ff">jvmarg</font><font color="#0000ff"> </font><font
 color="#0000ff">value=</font><font color="#3333ff">"</font><font
 color="#3333ff">-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Jdk14Logger</font><font
 color="#3333ff">"</font><font color="#0000ff">/&gt;</font><br>         <font
 color="#0000ff">&lt;</font><font color="#0000ff">jvmarg</font><font
 color="#0000ff"> </font><font color="#0000ff">value=</font><font
 color="#3333ff">"</font><font color="#3333ff">-Djava.util.logging.config.file=logging.properties</font><font
 color="#3333ff">"</font><font color="#0000ff">/&gt;</font><br>      <font
 color="#0000ff">&lt;</font><font color="#0000ff">/</font><font
 color="#000000"><strong>java</strong></font><font color="#0000ff">&gt;</font>   <br></pre>
<br>
See the code example below for how to set up a named logger, such as
the DEBUG<br>
logger mentioned in the above example. More typically, a logger is
created per<br>
class, so within MyClass there may be a line like this:<br>
<br>
<code>Log log = LogFactory.getLog(MyClass.class);</code><br>
<br>
which is equivalent to <br>
<br>
<code>Log log = LogFactory.getLog(getClass().getName());</code><br>
<br>
Then settings in the configuration file can be set per class if needed,
for<br>
example:<br>
<br>
<code>my.package.MyClass.level=FINEST</code><br>
<br>
The commons-logging log levels correspond to the
java.util.logging.Level levels<br>
as follows:<br>
<br>
<code>fatal = Level.SEVERE<br>
error = Level.SEVERE<br>
warn = Level.WARNING<br>
info = Level.INFO<br>
debug = Level.FINE<br>
trace = Level.FINEST</code><br>
<br>
In the above example configuration file, notice that the DEBUG logger
has a log<br>
level of FINE. This means that "trace" messages will not be recorded.
Also, the<br>
default level for the ConsoleHandler is INFO, so "debug" messages will
not be<br>
visible in the console output. By changing the <code>.level </code>setting
to FINE
and adding<br>
<code>java.util.logging.ConsoleHandler.level=FINE</code>, debug
messages
will then appear in the<br>
console output.<br>
<br>
More details on settings for the ConsoleHandler and the FileHandler can
be found<br>
in the JDK API documentation.<br>
<br>
There is also a MemoryHandler, a SocketHandler, and a StreamHandler
available,<br>
see the JDK API documentation for details and specific properties.<br>
<br>
<span style="font-weight: bold;">To set up SimpleLog:</span><br>
Set this system property:<br>
<br>
<code>org.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog</code><br>
<br>
For example:<br>
<br>
<code>java
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
MyClass<br>
</code><br>
will cause MyClass to use the Simple logger.<br>
<br>
Simple implementation of Log that sends all enabled log messages,<br>
for all defined loggers, to System.err.&nbsp; The following system
properties<br>
are supported to configure the behavior of this logger:<br>
<br>
<code>org.apache.commons.logging.simplelog.defaultlog</code> -<br>
&nbsp;&nbsp;&nbsp; Default logging detail level for all instances of
SimpleLog.<br>
&nbsp;&nbsp;&nbsp; Must be one of ("trace", "debug", "info", "warn",
"error", or "fatal").<br>
&nbsp;&nbsp;&nbsp; If not specified, defaults to "info". <br>
<code>org.apache.commons.logging.simplelog.log.xxxxx</code> -<br>
&nbsp;&nbsp;&nbsp; Logging detail level for a SimpleLog instance named
"xxxxx".<br>
&nbsp;&nbsp;&nbsp; Must be one of ("trace", "debug", "info", "warn",
"error", or "fatal").<br>
&nbsp;&nbsp;&nbsp; If not specified, the default logging detail level
is used.<br>
<code>org.apache.commons.logging.simplelog.showlogname</code> -<br>
&nbsp;&nbsp;&nbsp; Set to <code>true </code>if you want the Log
instance name to be<br>
&nbsp;&nbsp;&nbsp; included in output messages. Defaults to <code>false</code>.<br>
<code>org.apache.commons.logging.simplelog.showShortLogname</code> -<br>
&nbsp;&nbsp;&nbsp; Set to <code>true </code>if you want the last
componet of the name to be<br>
&nbsp;&nbsp;&nbsp; included in output messages. Defaults to <code>true</code>.<br>
<code>org.apache.commons.logging.simplelog.showdatetime</code> -<br>
&nbsp;&nbsp;&nbsp; Set to <code>true </code>if you want the current
date and time<br>
&nbsp;&nbsp;&nbsp; to be included in output messages. Default is false.<br>
<br>
<br>
In addition to looking for system properties with the names specified<br>
above, the current implementation also checks for a class loader
resource named<br>
"<code>simplelog.properties</code>", and includes any matching
definitions<br>
from this resource (if it exists).<br>
<br>
<pre><font color="#990000"><strong>import</strong></font> org.apache.commons.logging.*;<br><font
 color="#990000"><strong>import</strong></font> org.apache.commons.logging.impl.*;<br></pre>
<pre><font color="#990099"><strong>public</strong></font> <font
 color="#000099"><strong>class</strong></font> LogTest<font
 color="#000000">{</font><br>   <font color="#990099"><strong>public</strong></font> <font
 color="#990099"><strong>static</strong></font> <font color="#000099"><strong>void</strong></font> main (String[] args) <font
 color="#000000">{</font><br>      <br>      <font color="#059900"><em>//</em></font><font
 color="#059900"><em> </em></font><font color="#059900"><em>set</em></font><font
 color="#059900"><em> </em></font><font color="#059900"><em>up</em></font><font
 color="#059900"><em> </em></font><font color="#059900"><em>the</em></font><font
 color="#059900"><em> </em></font><font color="#059900"><em>loggers</em></font><br>      Log log <font
 color="#000000">=</font> LogFactory.<font color="#000000"><strong>getLog</strong></font>(<font
 style="color: rgb(0, 0, 0);" color="#3333ff">LogTest.class</font>);<br>      Log debug <font
 color="#000000">=</font> LogFactory.<font color="#000000"><strong>getLog</strong></font>(<font
 color="#3333ff">"</font><font color="#3333ff">DEBUG</font><font
 color="#3333ff">"</font>);<br>      <br>      <font color="#059900"><em>//</em></font><font
 color="#059900"><em> </em></font><font color="#059900"><em>tell</em></font><font
 color="#059900"><em> </em></font><font color="#059900"><em>what</em></font><font
 color="#059900"><em> </em></font><font color="#059900"><em>they</em></font><font
 color="#059900"><em> </em></font><font color="#059900"><em>are</em></font><br>      System.out.<font
 color="#000000"><strong>println</strong></font>(<font color="#3333ff">"</font><font
 color="#3333ff">log</font><font color="#3333ff"> </font><font
 color="#3333ff">is</font><font color="#3333ff"> </font><font
 color="#3333ff">a</font><font color="#3333ff"> </font><font
 color="#3333ff">"</font> <font color="#000000">+</font> log.<font
 color="#000000"><strong>getClass</strong></font>().<font
 color="#000000"><strong>getName</strong></font>());<br>      System.out.<font
 color="#000000"><strong>println</strong></font>(<font color="#3333ff">"</font><font
 color="#3333ff">debug</font><font color="#3333ff"> </font><font
 color="#3333ff">is</font><font color="#3333ff"> </font><font
 color="#3333ff">a</font><font color="#3333ff"> </font><font
 color="#3333ff">"</font> <font color="#000000">+</font> debug.<font
 color="#000000"><strong>getClass</strong></font>().<font
 color="#000000"><strong>getName</strong></font>());<br>      <br>      <br>      log.<font
 color="#000000"><strong>info</strong></font>(<font color="#3333ff">"</font><font
 color="#3333ff">an</font><font color="#3333ff"> </font><font
 color="#3333ff">info</font><font color="#3333ff"> </font><font
 color="#3333ff">message</font><font color="#3333ff">"</font>);<br>      debug.<font
 color="#000000"><strong>debug</strong></font>(<font color="#3333ff">"</font><font
 color="#3333ff">a</font><font color="#3333ff"> </font><font
 color="#3333ff">debug</font><font color="#3333ff"> </font><font
 color="#3333ff">message</font><font color="#3333ff">"</font>);<br><br>      log.<font
 color="#000000"><strong>info</strong></font>(<font color="#3333ff">"</font><font
 color="#3333ff">another</font><font color="#3333ff"> </font><font
 color="#3333ff">info</font><font color="#3333ff"> </font><font
 color="#3333ff">message</font><font color="#3333ff">"</font>);<br>      debug.<font
 color="#000000"><strong>debug</strong></font>(<font color="#3333ff">"</font><font
 color="#3333ff">another</font><font color="#3333ff"> </font><font
 color="#3333ff">debug</font><font color="#3333ff"> </font><font
 color="#3333ff">message</font><font color="#3333ff">"</font>);<br>      <br>   <font
 color="#000000">}</font><br><font color="#000000">}</font>
</pre>
</body>
</html>
